<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Basic Placeholder Usage - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/learning.view.placeholders.basics.html">Inglês (English)</a></li>
    <li><a href="../pt-br/learning.view.placeholders.basics.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="learning.view.placeholders.intro.html">Introduction</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="learning.view.placeholders.html">Getting Started Zend_View Placeholders</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="learning.view.placeholders.standard.html">Standard Placeholders</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="learning.view.placeholders.basics" class="section"><div class="info"><h1 class="title">Basic Placeholder Usage</h1></div>
    

    <p class="para">
        Zend Framework defines a generic  <span class="methodname">placeholder()</span> view helper that you
        may use for as many custom placeholders you need. It also provides a variety of specific
        placeholder implementations for often-needed functionality, such as specifying the
        <em class="emphasis">DocType</em> declaration, document title, and more.
    </p>

    <p class="para">
        All placeholders operate in roughly the same way. They are containers, and thus allow you to
        operate on them as collections. With them you can:
    </p>

    <ul class="itemizedlist">
        <li class="listitem">
            <p class="para">
                <em class="emphasis">Append</em> or <em class="emphasis">prepend</em> items to the collection.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <em class="emphasis">Replace</em> the entire collection with a single value.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                Specify a string with which to <em class="emphasis">prepend output</em> of the collection
                when rendering.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                Specify a string with which to <em class="emphasis">append output</em> of the collection
                when rendering.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                Specify a string with which to <em class="emphasis">separate items</em> of the collection
                when rendering.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <em class="emphasis">Capture content</em> into the collection.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <em class="emphasis">Render</em> the aggregated content.
            </p>
        </li>
    </ul>

    <p class="para">
        Typically, you will call the helper with no arguments, which will return a container on
        which you may operate. You will then either echo this container to render it, or call
        methods on it to configure or populate it. If the container is empty, rendering it will
        simply return an empty string; otherwise, the content will be aggregated according to the
        rules by which you configure it.
    </p>

    <p class="para">
        As an example, let&#039;s create a sidebar that consists of a number of &quot;blocks&quot; of content.
        You&#039;ll likely know up-front the structure of each block; let&#039;s assume for this example that
        it might look like this:
    </p>

    <pre class="programlisting brush: html">
&lt;div class=&quot;sidebar&quot;&gt;
    &lt;div class=&quot;block&quot;&gt;
        &lt;p&gt;
            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus
            consectetur aliquet odio ac consectetur. Nulla quis eleifend
            tortor. Pellentesque varius, odio quis bibendum consequat, diam
            lectus porttitor quam, et aliquet mauris orci eu augue.
        &lt;/p&gt;
    &lt;/div&gt;
    &lt;div class=&quot;block&quot;&gt;
        &lt;ul&gt;
            &lt;li&gt;&lt;a href=&quot;/some/target&quot;&gt;Link&lt;/a&gt;&lt;/li&gt;
            &lt;li&gt;&lt;a href=&quot;/some/target&quot;&gt;Link&lt;/a&gt;&lt;/li&gt;
        &lt;/ul&gt;
    &lt;/div&gt;
&lt;/div&gt;
</pre>


    <p class="para">
        The content will vary based on the controller and action, but the structure will be the
        same. Let&#039;s first setup the sidebar in a resource method of our bootstrap:
    </p>

    <pre class="programlisting brush: php">
class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
{
    // ...

    protected function _initSidebar()
    {
        $this-&gt;bootstrap(&#039;View&#039;);
        $view = $this-&gt;getResource(&#039;View&#039;);

        $view-&gt;placeholder(&#039;sidebar&#039;)
             // &quot;prefix&quot; -&gt; markup to emit once before all items in collection
             -&gt;setPrefix(&quot;&lt;div class=\&quot;sidebar\&quot;&gt;\n    &lt;div class=\&quot;block\&quot;&gt;\n&quot;)
             // &quot;separator&quot; -&gt; markup to emit between items in a collection
             -&gt;setSeparator(&quot;&lt;/div&gt;\n    &lt;div class=\&quot;block\&quot;&gt;\n&quot;)
             // &quot;postfix&quot; -&gt; markup to emit once after all items in a collection
             -&gt;setPostfix(&quot;&lt;/div&gt;\n&lt;/div&gt;&quot;);
    }

    // ...
}
</pre>


    <p class="para">
        The above defines a placeholder, &quot;sidebar&quot;, that has no items. It configures the basic
        markup structure of that placeholder, however, per our requirements.
    </p>

    <p class="para">
        Now, let&#039;s assume for the &quot;user&quot; controller that for all actions we&#039;ll want a block at the
        top containing some information. We could accomplish this in two ways: (a) we could add the
        content to the placeholder directly in the controller&#039;s
         <span class="methodname">preDispatch()</span> method, or (b) we could render a view script from
        within the  <span class="methodname">preDispatch()</span> method. We&#039;ll use (b), as it follows a
        more proper separation of concerns (leaving view-related logic and functionality within a
        view script).
    </p>

    <p class="para">
        We&#039;ll name the view script &quot;<var class="filename">user/_sidebar.phtml</var>&quot;, and populate it as
        follows:
    </p>

    <pre class="programlisting brush: php">
&lt;?php $this-&gt;placeholder(&#039;sidebar&#039;)-&gt;captureStart() ?&gt;
&lt;h4&gt;User Administration&lt;/h4&gt;
&lt;ul&gt;
    &lt;li&gt;&lt;a href=&quot;&lt;?php $this-&gt;url(array(&#039;action&#039; =&gt; &#039;list&#039;)) ?&gt;&quot;&gt;
        List&lt;/a&gt;&lt;/li&gt;
    &lt;li&gt;&lt;a href=&quot;&lt;?php $this-&gt;url(array(&#039;action&#039; =&gt; &#039;create&#039;)) ?&gt;&quot;&gt;
        Create&lt;/a&gt;&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;?php $this-&gt;placeholder(&#039;sidebar&#039;)-&gt;captureEnd() ?&gt;
</pre>


    <p class="para">
        The above example makes use of the content capturing feature of placeholders. By default,
        content is appended as a new item in the container, allowing us to aggregate content. This
        example makes use of view helpers and static <acronym class="acronym">HTML</acronym> in order to generate
        markup, and the content is then captured and appended into the placeholder itself.
    </p>

    <p class="para">
        To invoke the above view script, we would write the following in our
         <span class="methodname">preDispatch()</span> method:
    </p>

    <pre class="programlisting brush: php">
class UserController extends Zend_Controller_Action
{
    // ...

    public function preDispatch()
    {
        // ...

        $this-&gt;view-&gt;render(&#039;user/_sidebar.phtml&#039;);

        // ...
    }

    // ...
}
</pre>


    <p class="para">
        Note that we&#039;re not capturing the rendered value; there&#039;s no need, as the entierty of that
        view is being captured into a placeholder.
    </p>

    <p class="para">
        Now, let&#039;s assume our &quot;view&quot; action in that same controller needs to present some
        information. Within the &quot;<var class="filename">user/view.phtml</var>&quot; view script, we might have
        the following snippet of content:
    </p>

    <pre class="programlisting brush: php">
$this-&gt;placeholder(&#039;sidebar&#039;)
     -&gt;append(&#039;&lt;p&gt;User: &#039; . $this-&gt;escape($this-&gt;username) .  &#039;&lt;/p&gt;&#039;);
</pre>


    <p class="para">
        This example makes use of the  <span class="methodname">append()</span> method, and passes it some
        simple markup to aggregate.
    </p>

    <p class="para">
        Finally, let&#039;s modify our layout view script, and have it render the placeholder.
    </p>

    <pre class="programlisting brush: php">
&lt;html&gt;
&lt;head&gt;
    &lt;title&gt;My Site&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
    &lt;div class=&quot;content&quot;&gt;
        &lt;?php echo $this-&gt;layout()-&gt;content ?&gt;
    &lt;/div&gt;
    &lt;?php echo $this-&gt;placeholder(&#039;sidebar&#039;) ?&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>


    <p class="para">
        For controllers and actions that do not populate the &quot;sidebar&quot; placeholder, no content will
        be rendered; for those that do, however, echoing the placeholder will render the content
        according to the rules we created in our bootstrap, and the content we aggregated throughout
        the application. In the case of the &quot;<var class="filename">/user/view</var>&quot; action, and assuming a
        username of &quot;matthew&quot;, we would get content for the sidebar as follows (formatted for
        readability):
    </p>

    <pre class="programlisting brush: html">
&lt;div class=&quot;sidebar&quot;&gt;
    &lt;div class=&quot;block&quot;&gt;
        &lt;h4&gt;User Administration&lt;/h4&gt;
        &lt;ul&gt;
            &lt;li&gt;&lt;a href=&quot;/user/list&quot;&gt;List&lt;/a&gt;&lt;/li&gt;
            &lt;li&gt;&lt;a href=&quot;/user/create&quot;&gt;Create&lt;/a&gt;&lt;/a&gt;&lt;/li&gt;
        &lt;/ul&gt;
    &lt;/div&gt;
    &lt;div class=&quot;block&quot;&gt;
        &lt;p&gt;User: matthew&lt;/p&gt;
    &lt;/div&gt;
&lt;/div&gt;
</pre>


    <p class="para">
        There are a large number of things you can do by combining placeholders and layout scripts;
        experiment with them, and read the <a href="zend.view.helpers.html#zend.view.helpers.initial.placeholder" class="link">relevant manual sections</a> for more
        information.
    </p>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="learning.view.placeholders.intro.html">Introduction</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="learning.view.placeholders.html">Getting Started Zend_View Placeholders</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="learning.view.placeholders.standard.html">Standard Placeholders</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="learning.html">Learning Zend Framework</a></li>
  <li class="header up"><a href="learning.view.placeholders.html">Getting Started Zend_View Placeholders</a></li>
  <li><a href="learning.view.placeholders.intro.html">Introduction</a></li>
  <li class="active"><a href="learning.view.placeholders.basics.html">Basic Placeholder Usage</a></li>
  <li><a href="learning.view.placeholders.standard.html">Standard Placeholders</a></li>
  <li><a href="learning.view.placeholders.conclusion.html">View Placeholders: Conclusion</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>